Présentation de MarkIt v03

Introduction

Ceci est une présentation rapide du langage de marquage MarkIt. MarkIt est un prototype de langage de marquage conçu pour palier aux lacunes de MarkDown¹ ou ReST². MarkIt est développé avec le langage de programmation Haskell³ pour permettre un développement rapide, avoir un programme performant, fiable et portable.

Le but de MarkIt est de fournir un langage de marquage complet pour générer

des documents LaTeX
des pages HTML
des fichiers ODT (Open document files).

MarkIt supporte différentes structures et formatages tels que:

des listes à puces.
des listes numérotées.
des blocs de code.
des citations (expérimental).
des figures avec des légendes.
des images sur une ligne.
des commentaires.

La façon la plus simple d'utiliser MarkIt est:

D'écrire un fichier texte au format MarkIt avec n'importe quel éditeur de texte.
Lire le fichier avec le programme pour le tester et détecter d'éventuelles erreurs.
Générer le fichier de sortie avec un compilateur dédié pour générer:
- Un fichier HTML .html.
- Un fichier LaTeX .tex compilable avec pdflatex ou xelatex⁴.
- Un fichier OpenDocument .odt lisible et éditable avec LibreOffice ou MSOffice.
Différents types de documents standards peuvent être générés pour différents usages:
Article /

Un article est composé d'un unique fichier MarkIt. Un article est adapté pour rédiger une note de calcul, une procédure, un compte rendu, …

Report /
Un rapport est composé de plusieurs fichiers MarkIt agencés en différentes sections.
1. La page de garde
2. Le préambule. Pour rédiger une introduction.
3. Le corps du rapport. Chaque fichier constitue un chapitre.
4. Le postambule. Pour rédiger une conclusion.
5. Des annexes⁵.
Book /

Pour écrire un livre

Structure d'un document

En tête du fichier

L'en tête du fichier est la première partie du document.

L'en tête contient les informations sur la création du document. Les informations courantes sont:

Le titre du document (Obligatoire)
L'auteur (Obligatoire)
La date de création (Obligatoire)
Des mots clefs (Facultatif)
Un identifiant de documents (Facultatif)

L'en tête commence et se termine par 3 tirets ---

L'en tête de ce document est:

---
title: Présentation de MarkIt v03
authors: Jean-Luc JOULIN
date : 2021/04/21
keywords:MarkIt, Presentation, LaTeX, Markdown, ReST, Markup, Math, Ingéniérie
docref:introduction-to-markit-v03
---

Les blocs

Un document est constitué de blocs séparées par une ou plusieurs lignes vides qui apporte une représentation spécifique.

Les principaux blocs sont:

Les paragraphes
Les listes
Les titres
Les environnements
Les blocs de code
Les citations
Les commentaires

Les contenus de blocs (Inlines)

Les contenus de blocs peuvent être librement utilisés dans les blocs. Ils apportent différentes fonctions:

Modification du style de texte:
- Gras
- Italique
- Soulignement
- …
Créer des références aux autres éléments:
- Liens vers des sites internet.
- Liens vers des figures ou des titres.
- Référence bibliographique.
Des images.

Détail des éléments

Éléments blocs

Les blocs sont les éléments de base pour organiser et structurer un document. Les blocs sont séparés par une ou plusieurs lignes vides et ont un affichage différent en sortie.

Les blocs sont constitués d'éléments lignes (Voir plus loin) et doivent être au même niveau d'indentation.

Paragraphs

C'est le bloc de base. Il est composé de plusieurs lignes de chaînes de caractères. Voici un exemple de paragraphe:

Blocks are the basics way to organize the code.
Blocks are separated by 1 or more
blanklines and have a different behaviour
on the output.

Blocks are made of inlines (see bellow)
and must be used with the same indentation.

Pour commencer un nouveau paragraphe, laissez un ou plusieurs lignes vides entre eux.

Les titres

Les blocs titre permetttent de strcturer le documents en différentes sections

Un titre est définit sur une ligne unique souligné par une série de caractères. Suivant le caractère utilisé, le niveau de section sera différent.

Section
#######

Sous section
============

Sous sous section
-----------------

Sous sous sous section
^^^^^^^^^^^^^^^^^^^^^^

Pour l'instant 4 niveaux de sections peuvent être utilisés.

Listes à puces

Il est possible de produire une liste à puce en utilisant une succession de paragraph indentés commençant par un astérisque *. L'asterique ne doit pas être indenté⁶.

Le type de puces est définit par le style du document pendant la phase de compilation et ne peut pas être changé par l'utilisateur⁷.

Ci-dessous, un exemple de liste à puce:

* Premier élément de la liste à puce.

* Deuxième élément de la liste à puce.
  Plus d'informations
  
  D'autres informations.

Listes numérotées

Il est possible de produire une liste à puce en utilisant une succession de paragraph indentés commençant par un dièse #. Le dièse ne doit pas être indenté⁶.

Le type de numérotation est définit par le style du document pendant la phase de compilation et ne peut pas être changé par l'utilisateur⁷.

Ci-dessous, un exemple de liste numérotée:

# Premier élément de la liste à puce.

# Deuxième élément de la liste à puce.
  Plus d'informations
  
  D'autres informations.

Bloc de subsitution

Un bloc de subsitution est utilisé pour décrir un morceau de document qui peut être appelé n'importe ou dans le document par la commande :[ident].

Un bloc de substitution commence par [identifier]: et est suivi par une liste de blocs indentés.

Ci dessous, une liste de bloc de substitution:

[ident]:
  Un bloc de subsitution est utilisé pour décrir un morceau de document qui
  peut être appelé n'importe ou dans le document par la commande `:[ident]`.

  Un bloc de substitution commence par `[identifier]:` et est suivi par une liste de blocs indentés.

L'environnement figure

L'environnement figure permet à l'utilisateur de placer une image dans le document avec plusieurs options pour parfaire le résultat. Comme options, on a:

:file: :: (obligatoire) pour indiquer la localisation du fichier image.
:title: :: (obligatoire) Pour donner un titre à la figure.
:width: :: pour fixer la largeur de l'image. Cette largeur peut s'exprimer en cm ou %.
:ref: :: pour donner un identifiant à la figure et pouvoir créer des liens vers elle.

Le code ci-dessous permet de générer les figures qui suivent

::figure
  :file: EPR-854x569.jpg
  :title: A photography of the EPR vessel in jpeg format (default width)
  :ref: firstfigure

::figure
  :file: IRSN-schema-cuve-EPR.png
  :title: A scheme of the EPR vessel in png format (width = 50% of line width)
  :ref: secondfigure
  :width: 50%

::figure
  :file: cuve-epr_image.jpg
  :title: Another photography of the EPR vessel in jpeg format (fixed width to 2 centimeter)
  :ref: anotherfigure
  :width: 2cm

Figure 1 : Une photographie de la cuve d'un réacteur EPR au format jpeg (largeur par défaut).

Figure 2 : Un schéma de la cuve EPR au format png (largeur fixé à 50% de la largeur de la ligne).

Figure 3 : Une autre photographie de la cuve EPR au format jpeg (largeur fixé à 2cm).

MarkIt ces format d'image courant⁸:

Le format PNG (non destructif) pour les schémas, les captures d'écrans, … .
Le format jpeg (destructif) pour les photographies.
Le format eps (vectoriel) devrait normalement être disponible.

Les citations

Il est possible de citer du texte, des messages ou des mails en créant un bloc dont les lignes commences par >

Par exemple :

Bonjour,

Je fais suite à votre entretien chez tartempion.

Nous vous remercions de l’intérêt que vous avez porté à notre société.

Cependant, nous avons le regret de vous informer que nous ne pourrons pas répondre favorablement à vos attentes, d’autres candidats correspondant davantage au profil que nous recherchons.

Nous espérons que vos démarches aboutiront rapidement et vous prions de recevoir nos sincères salutations.

Bien cordialement.

généré avec le code :

> Bonjour,
> 
> Je fais suite à votre entretien chez tartempion.
> 
> Nous vous remercions de l’intérêt que vous avez porté à notre société.
> 
> Cependant, nous avons le regret de vous informer que nous ne pourrons
> pas répondre favorablement à vos attentes, d’autres candidats
> correspondant davantage au profil que nous recherchons.
> 
> Nous espérons que vos démarches aboutiront rapidement
> et vous prions de recevoir nos sincères salutations.
> 
> Bien cordialement.

A ce stade de développement, il n'éxiste pas encore de niveaux de citations

Commentaires

Il est possible d'inclure dans le document des commentaires pour apporter des précisions et des explications aux futurs rédacteurs du document en créant un bloc dont les lignes commences par //.

Par défaut ces commentaires ne seront pas affichés lors de la compilation du document. Toutefois, un option permettra d'afficher les commentaires de différentes manières

Note: Les commentaires ne peuvent pas être mis en fin de ligne.

// Un exemple de commentaire
// Bien penser à faire ceci et cela

Les éléments de texte (Inlines)

Texte en gras

On peut écrire du texte en gras en entourant le texte avec un double astérisque ** comme ceci **texte en gras**, ce qui donne le résultat suivant:

Du texte standard et un peu de texte en gras.

Emphases

On peut écrire du texte en emphase en entourant le texte avec un seul astérisque * comme ceci **texte en emphase**, ce qui donne le résultat suivant:

Du texte standard et un peu de texte en emphase.

Soulignement

On peut écrire du texte souligné en entourant le texte avec un deux tirets bas (underscore) __ comme ceci __texte souligné__, ce qui donne le résultat suivant:

Du texte standard et un peu de texte souligné.

Texte barré

On peut écrire du texte barré en entourant le texte avec un deux tildes ~~ comme ceci ~~texte barré~~, ce qui donne le résultat suivant:

Du texte standard et ~~un peu de texte barré~~.

Indices

On peut écrire du texte sous forme d'indice en entourant le texte avec un seul tiret bas (underscore) _ comme ceci _texte en indice_, ce qui donne le résultat suivant:

Du texte standard et _{un peu de texte en indice}.

Exposants

On peut écrire du texte sous forme d'exposant en entourant le texte avec un accent criconflexe ^ comme ceci ^texte en exposant^, ce qui donne le résultat suivant:

Du texte standard et ^{un peu de texte en exposant}.

Liens

Il est possible de créer des liens externes vers des adresses internet, ou des liens internes vers des titres, des images ou des documents

La façon générale est d'utiliser la commande @[lien] que l'on peut compléter avec du texte de substitution entre parenthèses @[lien](texte de substitution)

Pour créer un lien vers mon site internet, ou un autre lien vers _mon site internet avec des effets de style

Ces liens sont créés avec les commandes suivantes

@[http://www.jeanjoux.fr/](lien vers mon site internet)

@[http://www.jeanjoux.fr/](un autre *lien* vers __mon__ **site internet** avec des effets de style)

Les liens permettent également de créer une connexion vers une référence (identifiant)

Voici quelques liens pointant vers différentes parties de cet document:

Lien vers la figure 3 : figure 3

Lien vers la figure 1 : figure 1

Lien vers la section "Introduction" : §I

Lien vers la sous section "Blocks elements" : §III.1

Lien vers la sous sous section "Footnotes" : §III.2.j

Lien vers la sous sous section "Bullet list blocks" : §III.1.c

Lien vers le paragraphe traitant des références : !!! ID introduction-to-markit-fr-v03:ref not found !!!

References

Il est possible de créer des référence vers certaines parties du document avec la commande !!! Missing inline case !!! #[ref] et créer des liens n'importe ou avec @[ref]

Images sur ligne

Il est possible d'inclure des images dans un paragraphe avec la commande ![fichier] et préciser un texte de remplacement (si l'image n'est pas accessible)

Un image inclus dans un paragraphe voit sa hauteur fixée par défaut à la taille de la fonte utilisée et ne peut pas être modifié. Quelques exemples d'images en mode "ligne":

La hauteur de ces images est fixé car elles sont au milieu d'un texte. Il existe un cas particulier ou des images sur lignes sont inclus dans un paragraphe sans aucun texte. Dans ce cas, les image sont en mode "bloc" et ont leur largeur ajustée proportionnelement au nombre d'images se trouvant sur la même ligne.

Cela permet de présenter des vues alignées avec la même taille:

générés avec les commandes :


![thumb-up.png](thumb up picture)![warning.png](warning symbol)![radioactive2.png](radioactive symbol)

ou bien :


![thumb-up.png](thumb up picture)
![warning.png](warning symbol)
![radioactive2.png](radioactive symbol)

Notez qu'il n'y a pas d'options pour modifier la taille et créer des identifiants sur ces images (Contrairement aux figures).

Notes de bas de pages

Des notes de bas de page peuvent être créées en utilisant la commande ^[identifiant]. Les identifiant des notes sont uniques et sont utilisée pour identifier les notes de bas de page. Le contenu de la note doit être décrit dans un blocs ressemblant au bloc de substitution mais avec le symbole ^ au lieu de :.

Par exemple, pour créer un note de bas de page on aura:

Le type de puces est définit par le style du document pendant la phase de compilation
et ne peut pas être changé par l'utilisateur^[bulletlistdifference2].

[bulletlistdifference2]^
  Ceci est différent des autres langages de marquage ou le type de puce et de numéro
  est défini pas l'utilisateur

...

Si la commande ^[identifiant] se réfère à un identifiant qui n'a pas été décrit dans un bloc, une erreur sera renvoyée par le parser MarkIt

Formules mathématiques

Le but principal de MarkIt est de forunir un support pour les formuiles mahématiques pour les scientifiques et les ingénieurs. Les formules mathématiques doivent être écrites entre deux dollars $ en utilisant un langage spécifique proche de celui de LibreOffice^[mathlang

Les formules mathématiques peuvent écrite sur une ligne à l'intérieur d'un paragraphe de texte ou bien sur un ligne seule comme pour les images en lignes. De la même manière le comportement est différent suivant si on est sur une ligne contenant du texte ou non.

Si une formule est sur une ligne contenant du texte, elle sera en mode "ligne" sa hauteur sera de la même hauteur que la police de caractère.

Si elle est sont en mode "bloc" les paramètres standard d'affichage des formules mathématiques sont utilisées.

Quelques exemples de formules mathématiques en mode "ligne" $\frac{x^{2}}{a^{2}} + \frac{y^{2}}{b^{2}} = 1$ , $\sum_{a = 1}^{10} a = 55$ , $\int_{1}^{3} x^{2} d x$ générées avec le code suivant:

Quelques exemples de formules mathématiques en mode "ligne" ${x^2 over a^2}+{y^2 over b^2}=1$, $sum from {a=1} to {10} {a}=55$,
$int from {1} to {3} d{x} {x^2}$ générées avec le code suivant:

et ci dessous les mêmes en mode "bloc":

\frac{x^{2}}{a^{2}} + \frac{y^{2}}{b^{2}} = 1

\sum_{a = 1}^{10} a = 55

\int_{1}^{3} x^{2} d x

générées avec le code suivant:

${x^2 over a^2}+{y^2 over b^2}=1$

$sum from {a=1} to {10} {a}=55$

$int from {1} to {3} d{x} {x^2}$

et encore quelques exemples

\int_{1}^{3} x^{2} d x = {[\frac{x^{3}}{3}]}_{1}^{3} = \frac{27}{3} - \frac{1}{3} = \frac{26}{3}

\int_{1}^{3} x^{2} d x

{cos}^{2} (α) + {sin}^{2} (α) = 1

\vec{u} \land \vec{v} = (\begin{matrix} u_{2} v_{3} - u_{3} v_{2} \\ u_{3} v_{1} - u_{1} v_{3} \\ u_{1} v_{2} - u_{2} v_{1} \end{matrix})

Tableaux

MarkIt supporte les tableaux

Header 1	Header 2	Header 3	Header 4
Line 2	412.7	47235.45
Line 3	478.25	91.2	Une formule de trigonométrie simple ${cos}^{2} (α) + {sin}^{2} (α) = 1$
Line 4	762.74	915.45	35.2

Header 1	Header 2	Header 3rv ervew vervw	Header 4
Line 2	412.7	47235.45
Line 3egg seg	478.25	91.2	Une formule de trigonométrie simple ${cos}^{2} (α) + {sin}^{2} (α) = 1$
Line 4	762.74	915.45	35.2 ef zef ezg zgreg z

Notes

1.↑	Markdown ne supporte pas nativement les tableaux et les liens internes.
2.↑	ReST n'a pas de standard précis et est utilisé surtout pour le générateur de documentation Sphinx plutôt adapté à Python et l'utilitaire docutils.
3.↑	Haskell est vraiment un langage de programmation très puisant. Il est beaucoup plus fiable et rapide que Python. Il est typé fort et statiquement et permet de faire de l'inférence de type. Vous devriez vraiment songer à l'utiliser. En plus son logo est stylé Aller faire un tour sur le site officiel pour avoir plus d'information sur Haskell.
4.↑	La compilation avec XeTeX sera favorisée car `xelatex` est plus évolué que LaTeX.
5.↑	Pas encore implémenté!
6.↑	Ceci est différent des autres langages de marquage tels que MarkDown ou l'asterique doit être indenté.
7.↑	Ceci est différent des autres langages de marquage ou le type de puce et de numéro est défini pas l'utilisateur (`*` pour des puces, `-` pour des tirets, `I.` pour une numérotation en chiffre romain,…)
8.↑	Ce faible nombre de format est du à certaines limitations avec les compilateur en sortie et à la volonté d'uniformiser le formattage des documents Les images PDF images peuvent utilisées avec LaTeX mais pas avec LibreOffice. Le format wmf peut être utilisé avec LibreOffice mais pas avec LaTeX. La plupart des autres format d'images sont soit obsolètes soit trop peu utilisé. En tout état de cause, il est toujours possible de faire une conversion au bon format avec un logiciel de dessin.